home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / amok98-106 / amok105 / hotkey / hotkey.doc < prev    next >
Text File  |  1993-12-05  |  7KB  |  248 lines
  1. TABLE OF CONTENTS
  2.  
  3. HotKey/--background--
  4. HotKey/Activate
  5. HotKey/AddKey
  6. HotKey/CheckCVersion
  7. HotKey/DeleteBroker
  8. HotKey/GetCMsg
  9. HotKey/Init
  10. HotKey/--background--                                   HotKey/--background--
  11.  
  12.    DESCRIPTION
  13.     This module allows easy access to hotkey-specific functions of the
  14.     commodity.library.
  15.  
  16.    NOTE
  17.     DeleteBroker() and CheckCVersion() are the only procedures which
  18.     are very kind to OS1.x, because ONLY they are supposed to be called on
  19.     Operating Systems other than Release 2+.
  20.  
  21.     Therefore you MUST NOT call any of the module's
  22.     procedures except DeleteBroker() and CheckCVersion() on
  23.     Systems without commodities.library.
  24.  
  25.     In addition the version of commodities.library must be 37
  26.     or higher, because this version is demanded by Oberon 3.00 
  27.     Interfaces for the commodities.library
  28.     ( OpenLibrary(commodities.library,37) ).
  29.  
  30.     After version check failed, you may gracefully exit, e.g.
  31.       IF ~ CheckCVersion(0) THEN HALT(20) END;
  32.  
  33.     There should be no need to IMPORT Commodities, because all
  34.     important constants are redefined. Some constants are even
  35.     defined wrong in Interfaces for Oberon3.00!
  36.  
  37.  
  38.    EXAMPLE
  39.     Refer to HotKeyTest for a example how to use this module.
  40.  
  41.    AUTHOR
  42.     Program:  V1.0  28-Apr-92  Thomas Igracki
  43.                     first release
  44.               V2.0  21-Dec-92  Thomas Wagner [tom]
  45.                     removed some bugs (no ReplyMsg ...)
  46.                     and completely revised.
  47.                     NOTE: ** Interface has changed! **
  48.  
  49.     Autodocs: Thomas Wagner [tom]
  50.  
  51. HotKey/Activate                                               HotKey/Activate
  52.  
  53.    NAME
  54.     Activate -- (De)activates hotkeys
  55.  
  56.    SYNOPSIS
  57.     Activate (ON: BOOLEAN)
  58.  
  59.    FUNCTION
  60.     This function activates or deactivates the broker and its hotkeys.
  61.  
  62.    INPUTS
  63.     ON - TRUE to activate, FALSE to deactivate
  64.  
  65. HotKey/AddKey                                                   HotKey/AddKey
  66.  
  67.    NAME
  68.     AddKey -- Add a hotkey description to the broker
  69.  
  70.    SYNOPSIS
  71.     AddKey (descr: ARRAY OF CHAR; ID: LONGINT):BOOLEAN
  72.  
  73.    FUNCTION
  74.     Adds the given hotkey to the broker.
  75.  
  76.    INPUTS
  77.      descr - containing the hotkey description
  78.     ID    - any number to recognize this hotkey. Not
  79.             used by the module or by the operating system.
  80.  
  81.    RESULT
  82.     BOOLEAN - indicates the success of the hotkey installation. If
  83.               FALSE, ErrorSet contains the error code.
  84.               Note: Multiple error code bits are possible.
  85.               The most important error:
  86.                badDescription: wrong hotkey description
  87.  
  88.    SEE ALSO
  89.     GetCMsg()
  90.  
  91. HotKey/CheckCVersion                                     HotKey/CheckCVersion
  92.  
  93.    NAME
  94.     CheckCVersion -- Checks the version of the Commodities.library.
  95.  
  96.    SYNOPSIS
  97.     CheckCVersion (version: SHORTINT): BOOLEAN;
  98.  
  99.    FUNCTION
  100.       Check whether the required version is available.
  101.  
  102.    INPUTS
  103.     version - The required version. 0 to check if there is
  104.               any usable version of commodities.library available.
  105.               (See NOTE!).
  106.  
  107.    RESULT
  108.     BOOLEAN - TRUE  if Commodity has the required version or higher
  109.               FALSE if not available
  110.  
  111.    NOTE
  112.     V36 is considered out of date. So if you use the Interfaces for
  113.     commodity.library delivered with Oberon3.00 (or later versions)
  114.     CheckCVersion(0) will return FALSE!
  115.  
  116. HotKey/DeleteBroker                                       HotKey/DeleteBroker
  117.  
  118.    NAME
  119.     DeleteBroker -- Removes a broker
  120.  
  121.    SYNOPSIS
  122.     DeleteBroker()
  123.  
  124.    FUNCTION
  125.     This function removes the broker (and all attached hotkeys) and
  126.     closes the MsgPort.
  127.  
  128.    NOTES
  129.     This function is automatically called. No need to call it
  130.     yourself except you want to delete the broker earlier.
  131.  
  132.    SEE ALSO
  133.     Init()
  134.  
  135. HotKey/GetCMsg                                                 HotKey/GetCMsg
  136.  
  137.    NAME
  138.     GetCMsg -- Get commodity message
  139.  
  140.    SYNOPSIS
  141.     GetCMsg(VAR type: LONGSET; VAR id: INTEGER):BOOLEAN
  142.  
  143.    FUNCTION
  144.     If you get the signal (value returned by Init()) then you must
  145.     call GetCMsg() to determine which hotkey was pressed or which
  146.     command was sent.
  147.  
  148.    INPUTS
  149.     VAR type - Contains hotkey if an Hotkey was pressed or command
  150.                if a command was sent. Note: cDisable and cEnable
  151.                are handled automatically by this module. So you
  152.                should ignore them, except you want to add some
  153.                more functionality to them.
  154.     VAR id   - An integer value to store the id of a hotkey (if there
  155.                is any Msg). Only valid if type equals command.
  156.  
  157.    RESULT
  158.     BOOLEAN - TRUE if there was a Msg and type and id is valid.
  159.               Call GetCMsg() again, because there might be more Msg's.
  160.  
  161.    EXAMPLE
  162.     IMPORT Exec, HotKey;
  163.     VAR HotID  : LONGINT;
  164.         HotType: LONGSET;
  165.         HotSig : SHORTINT;
  166.         Signals: SHORTINT;
  167.     ...
  168.     IF ~HotKey.CheckCVersion(0) THEN HALT(20) END;
  169.     HotSig := HotKey.Init(...);
  170.     ...
  171.     Signals := Exec.Wait(LONGSET{HotSig});
  172.     ...
  173.     IF HotSig IN Signals THEN
  174.       WHILE HotKey.GetCMsg(HotType,HotID) DO
  175.            IF HotKey.hotkey IN HotType THEN
  176.           CASE HotID OF
  177.             ...
  178.           END; (* CASE *)
  179.         ELSIF HotKey.command IN HotType THEN
  180.           CASE HotID OF
  181.              hot.cAppear   : (* ShowInterface *) |
  182.             hot.cDisappear: (* HideInterface *) |
  183.             hot.cKill     : (* Quit          *) |
  184.              hot.cUnique   : (* ShowInterface or Quit *) |
  185.             ELSE            (* ignore cDisable and cEnable *)
  186.           END; (* CASE *)
  187.         END; (* IF *)
  188.       END; (* WHILE *)
  189.     END; (* IF *)
  190.  
  191.     For a full example see HotKeyTest.mod.
  192.  
  193. HotKey/Init                                                       HotKey/Init
  194.  
  195.    NAME
  196.     Init -- Initiate a broker.
  197.     InitX -- Initiate a broker (extended parameters).
  198.  
  199.    SYNOPSIS
  200.     InitX (name,title,descr: ARRAY OF CHAR;
  201.             unique          : SET;
  202.             window          : BOOLEAN;
  203.             pri             : SHORTINT       ): SHORTINT;
  204.  
  205.     Init (name,title,descr: ARRAY OF CHAR): SHORTINT;
  206.  
  207.    FUNCTION
  208.       Initiates some structures needed by all other procedures
  209.     of this module and installs a broker.
  210.  
  211.    INPUTS
  212.     name   - The name of the broker. You should not exceed the length
  213.              defined in Commodities.nameLen.
  214.     title  - Name, version, ... of the commodity. You should not exceed
  215.              the maximum length defined in Commodities.titleLen.
  216.     descr  - A short summary of the functionality of this commodity.
  217.              You should not exceed the length defined in
  218.              Commodities.descrLength.
  219.  
  220.     Only for InitX():
  221.  
  222.     unique - Set to one or more of Flags for Unique.
  223.               Init: set to {notify}.
  224.     window - Set this to TRUE when your commodity is able to open
  225.              a window. If this is set to FALSE the Show/Hide gadgets
  226.              of the exchange program are deactivated.
  227.              Init: set to TRUE.
  228.     pri    - The priority of the broker. Init: set to 0.
  229.  
  230.    RESULT
  231.     SHORTINT - A positive number is the Signalbit for hotkey
  232.                 activity. -1 indicates an error. See the global
  233.                readonly variable Error for the cause.
  234.                 Here are some important errors:
  235.                  systemError : usually no memory
  236.                  calledTwice : called this routine twice
  237.                  brokerNIL   : usually already another broker with
  238.                               same name
  239.  
  240.    NOTES
  241.     - After Init() or InitX() you must call Activate() to activate
  242.       the broker.
  243.     - You can't call Init() twice.
  244.  
  245.    SEE ALSO
  246.      DeleteBroker()
  247.  
  248.